Skip to content

docs(standards): scrub blog/docs fabrications from Story 13.6/13.7#30

Merged
matthew-on-git merged 1 commit intomainfrom
fix/blog-fabrications
May 7, 2026
Merged

docs(standards): scrub blog/docs fabrications from Story 13.6/13.7#30
matthew-on-git merged 1 commit intomainfrom
fix/blog-fabrications

Conversation

@matthew-on-git
Copy link
Copy Markdown
Contributor

Summary

A pass over everything I (Opus 4.7) wrote during the v1.10 + v1.11 release docs to remove invented details. Closes #29 (which only fixed the eighteen-months sentence).

v1.10 plugin-architecture blog

  • ❌ "first eighteen months of DevRail" → ✅ "Up to now". Project is ~2 months old.
  • ❌ "eight core ecosystems" but listed ten → ✅ "ten core ecosystems".
  • ❌ "We benchmarked Elixir + Rust + Swift in the same project and the second make check was within 200 ms" → removed (no benchmark run).
  • ❌ "Mojo. Zig. Roc. Crystal. Internal DSLs. Every one of these comes up in conversation" → removed (invented).
  • ❌ "first builds take 30 s -- 2 min depending on the plugin" → reframed (no measurement).
  • ❌ Broken design-doc URL → fixed.
  • ❌ "pip extras" survey claim → removed (design doc didn't survey pip).

v1.11 kotlin-as-reference-plugin blog

  • ❌ "(~5 minutes)" build time → reframed (no measurement).
  • ❌ "freshest core language ... well-tested ... 'I forget what this Dockerfile bit does'" → reframed.
  • ❌ "Its install script is the heaviest in the matrix" → softened (no comparison done).
  • ❌ "We'll likely ship them as separate v1.x minor releases so the migration burden is incremental rather than one big v2 cliff" → reframed; Story 13.9 actually retires all HAS_ blocks in one v2.0.0 cliff.
  • ❌ "Plus the manifest-shape side" → "On the manifest-shape side".

adding-a-plugin docs page

  • ❌ Broken design-doc URL → fixed.

Companion fixes (separate repos, not in this PR):

  • devrail-plugin-kotlin/README.md — same broken design-doc URL (committing on the kotlin repo's main).
  • OrgDocs/standards/contributing.md — same broken design-doc URL (in a separate MR).

🤖 Generated with Claude Code

Pass over everything I (Opus 4.7) wrote during the v1.10 + v1.11
release work. Issues found and fixed:

content/blog/2026-05-05-plugin-architecture.md (v1.10 release):
- "For the first eighteen months of DevRail" — DevRail's MVP closed
  2026-03-08; project is ~2 months old, not 18.
- "the eight core ecosystems" but enumerated ten — count drift.
- "We benchmarked Elixir + Rust + Swift in the same project and the
  second `make check` was within 200 ms of the first" — invented; no
  such benchmark was run.
- "Mojo. Zig. Roc. Crystal. Internal DSLs. Every one of these comes up
  in conversation" — invented; no such conversations.
- Design-doc URL pointed at `dev-toolchain/blob/main/docs/plugin-
  architecture.md` which doesn't exist; the real doc lives at
  `devrail-standards/blob/main/_bmad-output/planning-artifacts/`.
- "we surveyed Terraform providers, GitHub Actions, pre-commit, and
  pip extras" — design doc surveyed pre-commit, Terraform, GitHub
  Actions; not pip extras. Removed the pip claim.
- "first builds take 30 s -- 2 min depending on the plugin" —
  unmeasured timing. Replaced with a description of what dominates the
  build (install-script execution + apt + copy_from_builder payloads).

content/blog/2026-05-05-kotlin-as-reference-plugin.md (v1.11 release):
- "(~5 minutes)" build-time estimate — invented.
- "It's the freshest core language ... well-tested. Lower risk of 'I
  forget what this Dockerfile bit does.'" — invented framing.
- "Its install script is the heaviest in the matrix" — superlative
  comparison I did not actually do.
- "We'll likely ship them as separate v1.x minor releases so the
  migration burden is incremental rather than one big v2 cliff" —
  contradicts Story 13.9 which retires all HAS_<LANG> blocks at once
  in v2.0.0. Reframed to acknowledge the schedule isn't decided.
- "Plus the manifest-shape side: ..." — awkward leading word; moved
  to "On the manifest-shape side, ...".

content/docs/contributing/adding-a-plugin.md (Story 13.6 docs):
- Same broken design-doc URL; corrected.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@matthew-on-git matthew-on-git merged commit cd7b576 into main May 7, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant